<?php
/**
 * An object with key/value pairs. Each key can only have one value.
 * 
 * @package be.appcraft.util
 * @version $Revision: 1.1 $
 * 
 * @author Stijn Van Bael
 * @since 1.0
 */
interface Pageley_Util_Map extends IteratorAggregate {
	
	/**
	 * Gets the value for the specified key.
	 *
	 * @param object $key: the key
	 * 
	 * @return the object associated with the key, or null when the key does
	 * not exist
	 */
	public function get($key);
	
	/**
	 * Adds a value to the map with a default key. The key as an automatically
	 * assigned index starting with 0. With each call to add, the maximum index
	 * increases with one.
	 *
	 * @param object $value: the value to add
	 *
	 * @return a reference to this map
	 */
	public function add($value);
	
	/**
	 * Adds a value to the map with the associated key.
	 *
	 * @param object $key: the key
	 * @param object $value: the value 
	 * 
	 * @return a reference to this map
	 */
	public function put($key, $value);

	public function prepend($key, $value);
	
	/**
	 * Returns the number of key/value pairs in the map.
	 *
	 * @return the number of key/value pairs
	 */
	public function size();
	
	/**
	 * Returns the items of this map as an array.
	 * 
	 * @return the items as an array
	 */
	public function toArray();
	
	/**
	 * Checks whether or not a certain key exists in the map.
	 *
	 * @param object $key: the key
	 * 
	 * @return true when the key exists, false if not
	 */
	public function containsKey($key);
	
	/**
	 * Checks whether or not a certain value exists in the map.
	 *
	 * @param object $value: the value
	 * 
	 * @return true when the value exists, false if not
	 */
	public function containsValue($value);
	
	/**
	 * Removes the item with the specified key from the map.
	 *
	 * @param object $key: the key
	 * 
	 * @return a reference to this map 
	 */
	public function remove($key);
	
	/**
	 * Removes the specified value from the map.
	 *
	 * @param object $value: the value
	 * 
	 * @return a reference to this map 
	 */
	public function removeValue($value);
	
	/**
	 * Tests whether the Map is empty or not.
	 *
	 * @return true when the Map is empty, false otherwise
	 */
	public function isEmpty();
	
	public function reverse();
    
    public function clear();
    
    public function keys();
}